searchBox (InstantSearch.js v4)

A widget for InstantSearch.js that lets users enter a search query.

The searchBox widget lets users perform a text-based query.

The search box is usually the main entry point to start the search on an InstantSearch page. It’s usually placed at the top of a search experience, so users can start searching right away.

Usage

searchBox({
    container,
    // Optional parameters
    placeholder,
    autofocus,
    ignoreCompositionEvents,
    searchAsYouType,
    showReset,
    showSubmit,
    showLoadingIndicator,
    queryHook,
    templates,
    cssClasses
});

searchBox({
    container,
    // Optional parameters
    placeholder,
    autofocus,
    ignoreCompositionEvents,
    searchAsYouType,
    showReset,
    showSubmit,
    showLoadingIndicator,
    queryHook,
    templates,
    cssClasses
});

searchBox({
    container: '#searchbox',
});

Demo

Options

container · string · required

The CSS selector or HTML element to insert the widget into.

CSS selector

searchBox({
    container: '#searchbox',
});

placeholder · string

The placeholder text of the input.

searchBox({
    // ...
    placeholder: 'Search for products',
});

autofocus · boolean · default: "false"

Whether to automatically focus on the input when rendered.

searchBox({
    // ...
    autofocus: true,
});

ignoreCompositionEvents · boolean · default: "false"

Whether to update the search state in the middle of a composition session. This is useful when users need to search using non-Latin characters.

searchBox({
    // ...
    ignoreCompositionEvents: true,
});

Available from v4.64.2.

searchAsYouType · boolean · default: "true"

Whether to make a search on every change to the query. If false, new searches are only triggered by clicking the submit button or by pressing the Enter key in the search box.

searchBox({
    // ...
    searchAsYouType: false,
});

showSubmit · boolean · default: "false"

Whether to show the submit button.

searchBox({
    // ...
    showSubmit: false,
});

showReset · boolean · default: "false"

Whether to show the reset button.

searchBox({
    // ...
    showReset: false,
});

showLoadingIndicator · boolean · default: "true"

Whether to show the loading indicator (replaces the submit button if the search is stalled).

searchBox({
    // ...
    showLoadingIndicator: false,
});

queryHook · function

A function that’s called just before the search is triggered. It takes two parameters:

• query: string: the current query string
• search: function: a function to trigger the search.

If the search method isn’t called, no search is made to Algolia and the UI doesn’t refresh. If the search method is called, the widget is rendered.

This can be useful if you need to:

• Debounce searches to regulate requests.
• Programmatically alter the query before sending it to Algolia.

searchBox({
    // ...
    queryHook(query, search) {
    search(query);
    },
});

templates · object

The templates to use for the widget.

searchBox({
    // ...
    templates: {
    // ...
    },
});

You can customize parts of the widget’s UI with templates.

Every template provides an html function you can use as a tagged template. Using html lets you safely provide templates as an HTML string. It works directly in the browser without a build step. See more information, see Templating your UI.

The html function is available from InstantSearch v4.46.0.

Template parameters

submit · string (deprecated) or function · default: "true"

The template used for displaying the submit button.

Function

searchBox({
    // ...
    templates: {
    submit({ cssClasses }, { html }) {
        return html`<span class="${cssClasses.submit}">submit</span>`;
    },
    },
});

reset · string (deprecated) or function · default: "true"

The template used for displaying the reset button.

Function

searchBox({
    // ...
    templates: {
    reset({ cssClasses }, { html }) {
        return html`<span class="${cssClasses.reset}">reset</span>`;
    },
    },
});

loadingIndicator · string (deprecated) or function · default: "true"

The template used for displaying the loading indicator.

Function

searchBox({
    // ...
    templates: {
    loadingIndicator({ cssClasses }, { html }) {
        return html`<span class="${cssClasses.loadingIndicator}">loading</span>`;
    },
    },
});

cssClasses · object

The CSS classes you can override:

• root: the root element of the widget.
• form: the form element.
• input: the input element.
• reset: the reset button element.
• resetIcon: the reset button icon.
• loadingIndicator: the loading indicator element.
• loadingIcon: the loading indicator icon.
• submit: the submit button element.
• submitIcon: the submit button icon.

searchBox({
    // ...
    cssClasses: {
    root: 'MyCustomSearchBox',
    form: [
        'MyCustomSearchBoxForm',
        'MyCustomSearchBoxForm--subclass',
    ],
    },
});

HTML output

HTML

<div class="ais-SearchBox">
<form class="ais-SearchBox-form" novalidate>
    <input class="ais-SearchBox-input" autocomplete="off" autocorrect="off" autocapitalize="off" placeholder="Search for products" spellcheck="false" maxlength="512" type="search" value="" />
    <button class="ais-SearchBox-submit" type="submit" title="Submit the search query.">
    <svg class="ais-SearchBox-submitIcon" xmlns="http://www.w3.org/2000/svg" width="10" height="10" viewBox="0 0 40 40">
        ...
    </svg>
    </button>
    <button class="ais-SearchBox-reset" type="reset" title="Clear the search query." hidden>
    <svg class="ais-SearchBox-resetIcon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" width="10" height="10">
        ...
    </svg>
    </button>
    <span class="ais-SearchBox-loadingIndicator" hidden>
    <svg width="16" height="16" viewBox="0 0 38 38" xmlns="http://www.w3.org/2000/svg" stroke="#444" class="ais-SearchBox-loadingIcon">
        ...
    </svg>
    </span>
</form>
</div>

Connector

To create your own UI for the searchBox widget, use the connectSearchBox comnector.

Import it with a package manager or with a CDN.

Package manager

import { connectConfigure } from 'instantsearch.js/es/connectors';

import { connectConfigure } from 'instantsearch.js/es/connectors';

const { connectConfigure } = instantsearch.connectors;
// Or use instantsearch.connectors.connectConfigure()

After importing:

1. Create a render function

   This rendering function is called before the first search (init lifecycle step) and each time results come back from Algolia (render lifecycle step).

   const renderSearchBox = (renderOptions, isFirstRender) => {
       // Rendering logic
   };
   

   Render options

   query · string

   The query from the current search.

   const renderSearchBox = (renderOptions, isFirstRender) => {
   const { query, refine } = renderOptions;
   
   const container = document.querySelector('#searchbox');
   
   if (isFirstRender) {
       const input = document.createElement('input');
   
       input.addEventListener('input', event => {
       refine(event.target.value);
       });
   
       container.appendChild(input);
   }
   
   container.querySelector('input').value = query;
   };
   

   refine · function

   Sets a new query and triggers a new search.

   const renderSearchBox = (renderOptions, isFirstRender) => {
   const { query, refine } = renderOptions;
   
   const container = document.querySelector('#searchbox');
   
   if (isFirstRender) {
       const input = document.createElement('input');
   
       input.addEventListener('input', event => {
       refine(event.target.value);
       });
   
       container.appendChild(input);
   }
   
   container.querySelector('input').value = query;
   };
   

   clear · function

   Removes the query and triggers a new search.

   const renderSearchBox = (renderOptions, isFirstRender) => {
   const { query, refine, clear } = renderOptions;
   
   const container = document.querySelector('#searchbox');
   
   if (isFirstRender) {
       const input = document.createElement('input');
       const button = document.createElement('button');
       button.textContent = 'X';
   
       input.addEventListener('input', event => {
       refine(event.target.value);
       });
   
       button.addEventListener('click', () => {
       clear();
       });
   
       container.appendChild(input);
       container.appendChild(button);
   }
   
   container.querySelector('input').value = query;
   };
   

   isSearchStalled · boolean

   Returns true if the search results take more than a certain time to come back from Algolia servers. This can be configured on the instantsearch constructor with the attribute stalledSearchDelay.

   const renderSearchBox = (renderOptions, isFirstRender) => {
   const { query, refine, isSearchStalled } = renderOptions;
   
   const container = document.querySelector('#searchbox');
   
   if (isFirstRender) {
       const input = document.createElement('input');
       const loadingIndicator = document.createElement('span');
       loadingIndicator.textContent = 'Loading...';
   
       input.addEventListener('input', event => {
       refine(event.target.value);
       });
   
       container.appendChild(input);
       container.appendChild(loadingIndicator);
   }
   
   container.querySelector('input').value = query;
   container.querySelector('span').hidden = !isSearchStalled;
   };
   

   widgetParams · object

   All original widget options forwarded to the render function.

   const renderRangeInput = (renderOptions, isFirstRender) => {
   const { widgetParams } = renderOptions;
   
   widgetParams.container.innerHTML = '...';
   };
   
   // ...
   
   search.addWidgets([
   customRangeInput({
       container: document.querySelector('#searchbox'),
   })
   ]);
   

2. Create the custom widget

   When creating and instantiating a custom widget, there are two types of parameters you can give:

   • Instance parameters: predefined parameters that you can use to configure the behavior of Algolia.
   • Your own parameters: to make the custom widget generic.

   Both instance and custom parameters are available in connector.widgetParams, inside the renderFunction.

   const customSearchBox = connectSearchBox(
       renderSearchBox
   );
   

3. Instantiate

   customSearchBox({
   queryHook(query, search) {
       search(query);
   },
   });
   

   Instance options

   queryHook · function

   Use this is the same way as the queryHook option.

Connector example

// Create a render function
const renderSearchBox = (renderOptions, isFirstRender) => {
    const { query, refine, clear, isSearchStalled, widgetParams } = renderOptions;

    if (isFirstRender) {
    const input = document.createElement('input');

    const loadingIndicator = document.createElement('span');
    loadingIndicator.textContent = 'Loading...';

    const button = document.createElement('button');
    button.textContent = 'X';

    input.addEventListener('input', event => {
        refine(event.target.value);
    });

    button.addEventListener('click', () => {
        clear();
    });

    widgetParams.container.appendChild(input);
    widgetParams.container.appendChild(loadingIndicator);
    widgetParams.container.appendChild(button);
    }

    widgetParams.container.querySelector('input').value = query;
    widgetParams.container.querySelector('span').hidden = !isSearchStalled;
};

// Create custom widget
const customSearchBox = connectSearchBox(
    renderSearchBox
);

// Instantiate custom widget
search.addWidgets([
    customSearchBox({
    container: document.querySelector('#searchbox'),
    })
]);